To be completely honest I'd rather just update in two places, I have no idea what this is doing

Happy to take the installation update in the docs page though 👍

Just to make sure I understand correctly - the concern with importing importlib.metadata is regarding startup time? see comment

i feel uneasy about the global - do you have a reference from another project that does this?

Looking for __version__ = version(__name__) on github you will get many results

A couple of projects I know that made it in the first few pages of the list are:

• connector-x
• manim
• patito (in a try-except block)

Edit: some other project do the analogous of __version__ = version("narwhals") (but couldn't find something I know)

sure, thanks

still not sure we need it though - there's some other nice improvements in here though, happy to take those

regarding perf, from narwhals import __version__ currently takes 0m0.156s, and from importlib import metadata takes 0m0.108s

Some notes:

• __version__ doesn't seem to be mentioned as a standard in the python docs
  • I understand lots of packages seem to provide it anyway, but I'm not sure where the pattern is documented
• __getattr__ is a well-defined method of deferring imports
  • https://docs.python.org/3/reference/datamodel.html#customizing-module-attribute-access
• There are going to be many more examples of this pattern following 3.14
  • https://docs.python.org/3.14/whatsnew/3.14.html#optimizations
  • Improve import time of various stdlib modules python/cpython#118761
    • gh-118761: Lazily import annotationlib in typing python/cpython#132060
    • gh-118761: Reduce import time of gettext.py by delaying re import python/cpython#128898
    • gh-118761: Always lazy import re in locale python/cpython#129860

IMO, I don't think there's a use-case for checking narwhals.__version__, but if people want to do that - the cost of it isn't paid by everyone else since we're providing it lazily.
Are there any search results of a package checking it? (sorry I'm replying from my phone 😅)

@MarcoGorelli I understand your caution and ultimately will defer 😉 to you, but I think this balances:

• Theoretical backwards-compatibility
• Avoids introducing performance overhead for those that don't need it
• Ensures that potential cost is only paid once
• Lowers our maintenance burden, by simplifying version bumps

thanks - could you elaborate on the global part please? i've had a look at the linked projects and they don't seem to have it

if we don't deem __version__ to be useful to most users, presumably we don't need the global either?

thanks - could you elaborate on the global part please? i've had a look at the linked projects and they don't seem to have it

Sure @MarcoGorelli!

I'm assuming you're referring to the projects in (#2514 (comment))?
The 3 stdlib examples I gave in (#2514 (comment)) all featured use of global:

• https://github.com/python/cpython/pull/132060/files
• https://github.com/python/cpython/pull/128898/files
• https://github.com/python/cpython/pull/129860/files

As a more concrete example, we can do the following on main:

import narwhals as nw

>>> nw.__version__
'1.38.2'
>>> "__version__" in nw.__dict__
True
>>> nw.__dict__["__version__"]
'1.38.2'
>>> nw.__version__ == nw.__dict__["__version__"] == nw.__dict__.__getitem__("__version__")
True

But in this PR, we can see where the __getattr__ hook slips in:

import narwhals as nw

>>> nw.__dict__["__version__"]
KeyError: '__version__'
>>> nw.__version__
'1.38.2'
>>> nw.__dict__["__version__"]
'1.38.2'

Without the global:

• __version__ is never added to nw.__dict__
• Each lookup of nw.__version__ always goes via __getattr__, which is triggered after the regular __dict__ lookup fails

So the global is what provides the lazy import, since the work is only ever done once and only when a user asks for it 🙂.
All subsequent lookups behave identically to a regular lookup into the namespace.

As another example, polars has 2 behaviors related to __getattr__:

• Deprecations are triggered on every lookup
  • E.g. pl.NUMERIC_DTYPES
• Dependencies use much more magic than I understand 😄, but they eventually resolve to replacing a module's globals
  • https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L71-L76

Interestingly, polars seems to be fine with using find_spec and still considers that lazy

• https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L134
• https://github.com/pola-rs/polars/blob/34b5729cec09a8e3619c70844a77830c0613f070/py-polars/polars/dependencies.py#L173-L194